home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / misc / volume27 / dmake / part14 < prev    next >
Encoding:
Text File  |  1992-01-29  |  40.2 KB  |  1,112 lines

  1. Newsgroups: comp.sources.misc
  2. From: dvadura@plg.waterloo.edu (Dennis Vadura)
  3. Subject:  v27i115:  dmake - dmake Version 3.8, Part14/41
  4. Message-ID: <1992Jan28.031614.7638@sparky.imd.sterling.com>
  5. X-Md4-Signature: 87b7a6f27b823815f7ccf16c20ebecf8
  6. Date: Tue, 28 Jan 1992 03:16:14 GMT
  7. Approved: kent@sparky.imd.sterling.com
  8.  
  9. Submitted-by: dvadura@plg.waterloo.edu (Dennis Vadura)
  10. Posting-number: Volume 27, Issue 115
  11. Archive-name: dmake/part14
  12. Environment: Atari-ST, Coherent, Mac, MSDOS, OS/2, UNIX
  13. Supersedes: dmake: Volume 19, Issue 22-58
  14.  
  15. ---- Cut Here and feed the following to sh ----
  16. # this is dmake.shar.14 (part 14 of a multipart archive)
  17. # do not concatenate these parts, unpack them in order with /bin/sh
  18. # file dmake/man/dmake.nc continued
  19. #
  20. if test ! -r _shar_seq_.tmp; then
  21.     echo 'Please unpack part 1 first!'
  22.     exit 1
  23. fi
  24. (read Scheck
  25.  if test "$Scheck" != 14; then
  26.     echo Please unpack part "$Scheck" next!
  27.     exit 1
  28.  else
  29.     exit 0
  30.  fi
  31. ) < _shar_seq_.tmp || exit 1
  32. if test -f _shar_wnt_.tmp; then
  33. sed 's/^X//' << 'SHAR_EOF' >> 'dmake/man/dmake.nc' &&
  34. X          tion and to make all targets not depending on targets
  35. X          that could not be made. Ordinarily dmake stops after a
  36. X          command returns a non-zero status, specifying -k causes
  37. X          dmake to ignore the error and continue to make as much
  38. X          as possible.
  39. X
  40. X     -n   Causes dmake to print out what it would have executed,
  41. X          but does not actually execute the commands.  A special
  42. X          check is made for the string "$(MAKE)" inside a recipe
  43. X          line, if found, the line is expanded and invoked,
  44. X          thereby enabling recursive makes to give a full
  45. X
  46. X
  47. X
  48. Version 3.70                    UW                              2
  49. X
  50. X
  51. X
  52. X
  53. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  54. X
  55. X
  56. X
  57. X          description of all that they will do.  The check for
  58. X          "$(MAKE)" is disabled inside group recipes.
  59. X
  60. X     -p   Print out a version of the digested makefile in human
  61. X          readable form.  (useful for debugging, but cannot be
  62. X          re-read by dmake)
  63. X
  64. X     -P#  On systems that support multi-processing cause dmake to
  65. X          use # concurrent child processes to make targets.  See
  66. X          the "MULTI PROCESSING" section for more information.
  67. X
  68. X     -q   Check and see if the target is up to date.  Exits with
  69. X          code 0 if up to date, 1 otherwise.
  70. X
  71. X     -r   Tells dmake not to read the initial startup makefile,
  72. X          see STARTUP section for more details.
  73. X
  74. X     -s   Tells dmake to do all its work silently and not echo
  75. X          the commands it is executing to stdout (also suppresses
  76. X          warnings).  This  is equivalent to the .SILENT attri-
  77. X          bute or macro.
  78. X
  79. X     -S   Force sequential execution of recipes on architectures
  80. X          which support concurrent makes.  For backward compati-
  81. X          bility with old makefiles that have nasty side-effect
  82. X          prerequisite dependencies.
  83. X
  84. X     -t   Causes dmake to touch the targets and bring them up to
  85. X          date without executing any commands.  Note that targets
  86. X          will not be created if they do not already exist.
  87. X
  88. X     -T   Tells dmake to not perform transitive closure on the
  89. X          inference graph.
  90. X
  91. X     -u   Force an unconditional update.  (ie. do everything that
  92. X          would be done if everything that a target depended on
  93. X          was out of date)
  94. X
  95. X     -v[dfimt]
  96. X          Verbose flag, when making targets print to stdout what
  97. X          we are going to make and what we think its time stamp
  98. X          is.  The optional flags [dfimt] can be used to restrict
  99. X          the information that is displayed.  In the absence of
  100. X          any optional flags all are assumed to be given (ie. -v
  101. X          is equivalent to -vdfimt).  The meanings of the
  102. X          optional flags are:
  103. X
  104. X          d    Notify of change directory operations only.
  105. X
  106. X          f    Notify of file I/O operations only.
  107. X
  108. X
  109. X
  110. X
  111. X
  112. Version 3.70                    UW                              3
  113. X
  114. X
  115. X
  116. X
  117. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  118. X
  119. X
  120. X
  121. X          i    Notify of inference algorithm operation only.
  122. X
  123. X          m    Notify of target update operations only.
  124. X
  125. X          t    Keep any temporary files created; normally they
  126. X               are automatically deleted.
  127. X
  128. X     -V   Print the version of dmake, and values of builtin mac-
  129. X          ros.
  130. X
  131. X     -x   Upon processing the user makefile export all non-
  132. X          internally defined macros to the user's environment.
  133. X          This option together with the -e option allows SYSV
  134. X          AUGMAKE recursive makes to function as expected.
  135. X
  136. INDEX
  137. X     Here is a list of the sections that follow and a short
  138. X     description of each.  Perhaps you won't have to read the
  139. X     whole man page to find what you need.
  140. X
  141. X     STARTUP            Describes dmake initialization.
  142. X
  143. X     SYNTAX             Describes the syntax of makefile expres-
  144. X                        sions.
  145. X
  146. X     ATTRIBUTES         Describes the notion of attributes and
  147. X                        how they are used when making targets.
  148. X
  149. X     MACROS             Defining and expanding macros.
  150. X
  151. X     RULES AND TARGETS  How to define targets and their prere-
  152. X                        quisites.
  153. X
  154. X     RECIPES            How to tell dmake how to make a target.
  155. X
  156. X     TEXT DIVERSIONS    How to use text diversions in recipes and
  157. X                        macro expansions.
  158. X
  159. X     SPECIAL TARGETS    Some targets are special.
  160. X
  161. X     SPECIAL MACROS     Macros used by dmake to alter the pro-
  162. X                        cessing of the makefile, and those
  163. X                        defined by dmake for the user.
  164. X
  165. X     CONTROL MACROS     Itemized list of special control macros.
  166. X
  167. X     RUN-TIME MACROS    Discussion of special run-time macros
  168. X                        such as $@ and $<.
  169. X
  170. X     FUNCTION MACROS    GNU style function macros, only $(mktmp
  171. X                        ...) for now.
  172. X
  173. X
  174. X
  175. X
  176. Version 3.70                    UW                              4
  177. X
  178. X
  179. X
  180. X
  181. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  182. X
  183. X
  184. X
  185. X     DYNAMIC PREREQUISITES
  186. X                        Processing of prerequisites which contain
  187. X                        macro expansions in their name.
  188. X
  189. X     BINDING TARGETS    The rules that dmake uses to bind a tar-
  190. X                        get to an existing file in the file sys-
  191. X                        tem.
  192. X
  193. X     PERCENT(%) RULES   Specification of recipes to be used by
  194. X                        the inference algorithm.
  195. X
  196. X     MAKING INFERENCES  The rules that dmake uses when inferring
  197. X                        how to make a target which has no expli-
  198. X                        cit recipe.  This and the previous sec-
  199. X                        tion are really a single section in the
  200. X                        text.
  201. X
  202. X     MAKING TARGETS     How dmake makes targets other than
  203. X                        libraries.
  204. X
  205. X     MAKING LIBRARIES   How dmake makes libraries.
  206. X
  207. X     KEEP STATE         A discussion of how .KEEP_STATE works.
  208. X
  209. X     MULTI PROCESSING   Discussion of dmake's parallel make
  210. X                        facilities for architectures that support
  211. X                        them.
  212. X
  213. X     CONDITIONALS       Conditional expressions which control the
  214. X                        processing of the makefile.
  215. X
  216. X     EXAMPLES           Some hopefully useful examples.
  217. X
  218. X     COMPATIBILITY      How dmake compares with previous versions
  219. X                        of make.
  220. X
  221. X     LIMITS             Limitations of dmake.
  222. X
  223. X     PORTABILITY        Comments on writing portable makefiles.
  224. X
  225. X     FILES              Files used by dmake.
  226. X
  227. X     SEE ALSO           Other related programs, and man pages.
  228. X
  229. X     AUTHOR             The guy responsible for this thing.
  230. X
  231. X     BUGS               Hope not.
  232. X
  233. STARTUP
  234. X     When dmake begins execution it first processes the command
  235. X     line and then processes an initial startup-makefile.  This
  236. X     is followed by an attempt to locate and process a user
  237. X
  238. X
  239. X
  240. Version 3.70                    UW                              5
  241. X
  242. X
  243. X
  244. X
  245. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  246. X
  247. X
  248. X
  249. X     supplied makefile.  The startup file defines the default
  250. X     values of all required control macros and the set of default
  251. X     rules for making targets and inferences.  When searching for
  252. X     the startup makefile, dmake searches the following loca-
  253. X     tions, in the order specified, until a startup file is
  254. X     located:
  255. X
  256. X          1.   The location given as the value of the macro MAK-
  257. X               ESTARTUP defined on the command line.
  258. X
  259. X          2.   The location given as the value of the environment
  260. X               variable MAKESTARTUP defined in the current
  261. X               environment.
  262. X
  263. X          3.   The location given as the value of the macro MAK-
  264. X               ESTARTUP defined internally within dmake.
  265. X
  266. X     The above search is disabled by specifying the -r option on
  267. X     the command line.  An error is issued if a startup makefile
  268. X     cannot be found and the -r option was not specified.  A user
  269. X     may substitute a custom startup file by defining the MAKES-
  270. X     TARTUP environment variable or by redefining the MAKESTARTUP
  271. X     macro on the command line.  To determine where dmake looks
  272. X     for the default startup file, check your environment or
  273. X     issue the command "dmake -V".
  274. X
  275. X     A similar search is performed to locate a default user
  276. X     makefile when no -f command line option is specified.  By
  277. X     default, the prerequisite list of the special target
  278. X     .MAKEFILES specifies the names of possible makefiles and the
  279. X     search order that dmake should use to determine if one
  280. X     exists.  A typical definition for this target is:
  281. X
  282. X          .MAKEFILES : makefile.mk Makefile makefile
  283. X
  284. X     dmake will first look for makefile.mk and then the others.
  285. X     If a prerequisite cannot be found dmake will try to make it
  286. X     before going on to the next prerequisite.  For example,
  287. X     makefile.mk can be checked out of an RCS file if the proper
  288. X     rules for doing so are defined in the startup file.
  289. X
  290. X     If the first line of the user makefile is of the form:
  291. X
  292. X          #! command command_args
  293. X
  294. X     then dmake will expand and run the command prior to reading
  295. X     any addtional input.  If the return code of the command is
  296. X     zero then dmake will continue on to process the remainder of
  297. X     the user makefile, if the return code is non-zero then dmake
  298. X     will exit.
  299. X
  300. X
  301. X
  302. X
  303. X
  304. Version 3.70                    UW                              6
  305. X
  306. X
  307. X
  308. X
  309. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  310. X
  311. X
  312. X
  313. SYNTAX
  314. X     This section is a summary of the syntax of makefile state-
  315. X     ments.  The description is given in a style similar to BNF,
  316. X     where { } enclose items that may appear zero or more times,
  317. X     and [ ] enclose items that are optional.  Alternative pro-
  318. X     ductions for a left hand side are indicated by '->', and
  319. X     newlines are significant.  All symbols in bold type are text
  320. X     or names representing text supplied by the user.
  321. X
  322. X
  323. X
  324. X          Makefile -> { Statement }
  325. X
  326. X          Statement -> Macro-Definition
  327. X                    -> Conditional
  328. X                    -> Rule-Definition
  329. X                    -> Attribute-Definition
  330. X
  331. X          Macro-Definition -> MACRO = LINE
  332. X                           -> MACRO *= LINE
  333. X                           -> MACRO := LINE
  334. X                           -> MACRO *:= LINE
  335. X                           -> MACRO += LINE
  336. X                           -> MACRO +:= LINE
  337. X
  338. X          Conditional ->  .IF expression
  339. X                             Makefile
  340. X                          [ .ELIF expression
  341. X                             Makefile ]
  342. X                          [ .ELSE
  343. X                             Makefile ]
  344. X                          .END
  345. X
  346. X          expression -> LINE
  347. X                     -> STRING == LINE
  348. X                     -> STRING != LINE
  349. X
  350. X
  351. X          Rule-Definition ->  target-definition
  352. X                                 [ recipe ]
  353. X
  354. X          target-definition -> targets [attrs] op { PREREQUISITE } [; rcp-line]
  355. X
  356. X          targets -> target { targets }
  357. X                  -> "target" { targets }
  358. X
  359. X          target -> special-target
  360. X                 -> TARGET
  361. X
  362. X          attrs -> attribute { attrs }
  363. X                -> "attribute" { attrs }
  364. X
  365. X
  366. X
  367. X
  368. Version 3.70                    UW                              7
  369. X
  370. X
  371. X
  372. X
  373. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  374. X
  375. X
  376. X
  377. X          op -> : { modifier }
  378. X
  379. X          modifier -> :
  380. X                   -> ^
  381. X                   -> !
  382. X                   -> -
  383. X
  384. X          recipe -> { TAB rcp-line }
  385. X                 -> [@][%][-] [
  386. X                       { LINE }
  387. X                    ]
  388. X
  389. X          rcp-line -> [@][%][-][+] LINE
  390. X
  391. X
  392. X          Attribute-Definition -> attrs : targets
  393. X
  394. X
  395. X          attribute -> .EPILOG
  396. X                    -> .IGNORE
  397. X                    -> .LIBRARY
  398. X                    -> .MKSARGS
  399. X                    -> .NOINFER
  400. X                    -> .NOSTATE
  401. X                    -> .PHONY
  402. X                    -> .PRECIOUS
  403. X                    -> .PROLOG
  404. X                    -> .SETDIR=path
  405. X                    -> .SILENT
  406. X                    -> .SEQUENTIAL
  407. X                    -> .SWAP
  408. X                    -> .USESHELL
  409. X                    -> .SYMBOL
  410. X                    -> .UPDATEALL
  411. X
  412. X          special-target -> .ERROR
  413. X                         -> .EXPORT
  414. X                         -> .GROUPEPILOG
  415. X                         -> .GROUPPROLOG
  416. X                         -> .IMPORT
  417. X                         -> .INCLUDE
  418. X                         -> .INCLUDEDIRS
  419. X                         -> .MAKEFILES
  420. X                         -> .REMOVE
  421. X                         -> .SOURCE
  422. X                         -> .SOURCE.suffix
  423. X                         -> .suffix1.suffix2
  424. X
  425. X
  426. X     Where, TAB represents a <tab> character, STRING represents
  427. X     an arbitrary sequence of characters, and LINE represents a
  428. X     possibly empty sequence of characters terminated by a non-
  429. X
  430. X
  431. X
  432. Version 3.70                    UW                              8
  433. X
  434. X
  435. X
  436. X
  437. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  438. X
  439. X
  440. X
  441. X     escaped (not immediately preceded by a backslash '\') new-
  442. X     line character.  MACRO, PREREQUISITE, and TARGET each
  443. X     represent a string of characters not including space or tab
  444. X     which respectively form the name of a macro, prerequisite or
  445. X     target.  The name may itself be a macro expansion expres-
  446. X     sion.  A LINE can be continued over several physical lines
  447. X     by terminating it with a single backslash character.  Com-
  448. X     ments are initiated by the pound # character and extend to
  449. X     the end of line.  All comment text is discarded, a '#' may
  450. X     be placed into the makefile text by escaping it with '\'
  451. X     (ie. \# translates to # when it is parsed).  An exception to
  452. X     this occurs when a # is seen inside a recipe line that
  453. X     begins with a <tab> or is inside a group recipe.  If you
  454. X     specify the -c command line switch then this behavior is
  455. X     disabled and dmake will treat all # characters as start of
  456. X     comment indicators unless they are escaped by \.  A set of
  457. X     continued lines may be commented out by placing a single #
  458. X     at the start of the first line.  A continued line cannot
  459. X     span more than one makefile.
  460. X
  461. X     white space is defined to be any combination of <space>,
  462. X     <tab>, and the sequence \<nl> when \<nl> is used to ter-
  463. X     minate a LINE.  When processing macro definition lines, any
  464. X     amount of white space is allowed on either side of the macro
  465. X     operator (=, *=, :=, *:=, += or +:=), and white space is
  466. X     stripped from both before and after the macro value string.
  467. X     The sequence \<nl> is treated as white space during recipe
  468. X     expansion and is deleted from the final recipe string.  You
  469. X     must escape the \<nl> with another \ in order to get a \ at
  470. X     the end of a recipe line.  The \<nl> sequence is deleted
  471. X     from macro values when they are expanded.
  472. X
  473. X     When processing target definition lines, the recipe for a
  474. X     target must, in general, follow the first definition of the
  475. X     target (See the RULES AND TARGETS section for an exception),
  476. X     and the recipe may not span across multiple makefiles.  Any
  477. X     targets and prerequisites found on a target definition line
  478. X     are taken to be white space separated tokens.  The rule
  479. X     operator (op in SYNTAX section) is also considered to be a
  480. X     token but does not require white space to precede or follow
  481. X     it.  Since the rule operator begins with a `:', traditional
  482. X     versions of make do not allow the `:' character to form a
  483. X     valid target name.  dmake allows `:' to be present in
  484. X     target/prerequisite names as long as the entire
  485. X     target/prerequisite name is quoted.  For example:
  486. X
  487. X          a:fred : test
  488. X
  489. X     would be parsed as TARGET = a, PREREQUISITES={fred, :,
  490. X     test}, which is not what was intended.  To fix this you must
  491. X     write:
  492. X
  493. X
  494. X
  495. X
  496. Version 3.70                    UW                              9
  497. X
  498. X
  499. X
  500. X
  501. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  502. X
  503. X
  504. X
  505. X          "a:fred" : test
  506. X
  507. X     Which will be parsed as expected.  Quoted target and prere-
  508. X     quisite specifications may also contain white space thereby
  509. X     allowing the use of complex function macro expressions..
  510. X     See the EXAMPLES section for how to apply " quoting to a
  511. X     list of targets.
  512. X
  513. ATTRIBUTES
  514. X     dmake defines several target attributes.  Attributes may be
  515. X     assigned to a single target, a group of targets, or to all
  516. X     targets in the makefile.  Attributes are used to modify
  517. X     dmake actions during target update.  The recognized attri-
  518. X     butes are:
  519. X
  520. X
  521. X     .EPILOG     Insert shell epilog code when executing a group
  522. X                 recipe associated with any target having this
  523. X                 attribute set.
  524. X
  525. X     .IGNORE     Ignore an error when trying to make any target
  526. X                 with this attribute set.
  527. X
  528. X     .LIBRARY    Target is a library.
  529. X
  530. X     .MKSARGS    If running in an MSDOS environment then use MKS
  531. X                 extended argument passing conventions to pass
  532. X                 arguments to commands.  Non-MSDOS environments
  533. X                 ignore this attribute.
  534. X
  535. X     .NOINFER    Any target with this attribute set will not be
  536. X                 subjected to transitive closure if it is
  537. X                 inferred as a prerequisite of a target whose
  538. X                 recipe and prerequisites are being inferred.
  539. X                 (i.e. the inference algorithm will not use any
  540. X                 prerequisite with this attribute set, as a tar-
  541. X                 get) If specified as '.NOINFER:' (ie. with no
  542. X                 prerequisites or targets) then the effect is
  543. X                 equivalent to specifying -T on the command line.
  544. X
  545. X     .NOSTATE    Any target with this attribute set will not have
  546. X                 command line flag information stored in the
  547. X                 state file if .KEEP_STATE has been enabled.
  548. X
  549. X     .PHONY      Any target with this attribute set will have its
  550. X                 recipe executed each time the target is made
  551. X                 even if a file matching the target name can be
  552. X                 located.  Any targets that have a .PHONY attri-
  553. X                 buted target as a prerequisite will be made each
  554. X                 time the .PHONY attributed prerequisite is made.
  555. X
  556. X
  557. X
  558. X
  559. X
  560. Version 3.70                    UW                             10
  561. X
  562. X
  563. X
  564. X
  565. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  566. X
  567. X
  568. X
  569. X     .PRECIOUS   Do not remove associated target under any cir-
  570. X                 cumstances.  Set by default for any targets
  571. X                 whose corresponding files exist in the file sys-
  572. X                 tem prior to the execution of dmake.
  573. X
  574. X     .PROLOG     Insert shell prolog code when executing a group
  575. X                 recipe associated with any target having this
  576. X                 attribute set.
  577. X
  578. X     .SEQUENTIAL Force a sequential make of the associated
  579. X                 target's prerequisites.
  580. X
  581. X     .SETDIR     Change current working directory to specified
  582. X                 directory when making the associated target.
  583. X                 You must specify the directory at the time the
  584. X                 attribute is specified.  To do this simply give
  585. X                 .SETDIR=path as the attribute.  path is expanded
  586. X                 and the result is used as the value of the
  587. X                 directory to change to.  If path is surrounded
  588. X                 by single quotes then path is not expanded, and
  589. X                 is used literally as the directory name.  If the
  590. X                 path contains any `:' characters then the entire
  591. X                 attribute string must be quoted using ".  If a
  592. X                 target having this attribute set also has the
  593. X                 .IGNORE attribute set then if the change to the
  594. X                 specified directory fails it will be ignored,
  595. X                 and no error message will be issued.
  596. X
  597. X     .SILENT     Do not echo the recipe lines when making any
  598. X                 target with this attribute set, and do not issue
  599. X                 any warnings.
  600. X
  601. X     .SWAP       Under MSDOS when making a target with this
  602. X                 attribute set swap the dmake executable to disk
  603. X                 prior to executing the recipe line.  Also see
  604. X                 the '%' recipe line flag defined in the RECIPES
  605. X                 section.
  606. X
  607. X     .SYMBOL     Target is a library member and is an entry point
  608. X                 into a module in the library.  This attribute is
  609. X                 used only when searching a library for a target.
  610. X                 Targets of the form lib((entry)) have this
  611. X                 attribute set automatically.
  612. X
  613. X     .USESHELL   Force each recipe line of a target to be exe-
  614. X                 cuted using a shell.  Specifying this attribute
  615. X                 is equivalent to specifying the '+' character at
  616. X                 the start of each line of a non-group recipe.
  617. X
  618. X     .UPDATEALL  Indicates that all the targets listed in this
  619. X                 rule are updated by the execution of the accom-
  620. X                 panying recipe.  A common example is the
  621. X
  622. X
  623. X
  624. Version 3.70                    UW                             11
  625. X
  626. X
  627. X
  628. X
  629. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  630. X
  631. X
  632. X
  633. X                 production of the y.tab.c and y.tab.h files by
  634. X                 yacc when it is run on a grammar.  Specifying
  635. X                 .UPDATEALL in such a rule prevents the running
  636. X                 of yacc twice, once for the y.tab.c file and
  637. X                 once for the y.tab.h file.
  638. X
  639. X
  640. X     All attributes are user setable and except for .UPDATEALL,
  641. X     .SETDIR and .MKSARGS may be used in one of two forms.  The
  642. X     .MKSARGS attribute is restricted to use as a global attri-
  643. X     bute, and the use of the .UPDATEALL and .SETDIR attributes
  644. X     is restricted to rules of the second form only.
  645. X
  646. X          ATTRIBUTE_LIST : targets
  647. X
  648. X     assigns the attributes specified by ATTRIBUTE_LIST to each
  649. X     target in targets or
  650. X
  651. X          targets ATTRIBUTE_LIST : ...
  652. X
  653. X     assigns the attributes specified by ATTRIBUTE_LIST to each
  654. X     target in targets. In the first form if targets is empty
  655. X     (ie. a NULL list), then the list of attributes will apply to
  656. X     all targets in the makefile (this is equivalent to the com-
  657. X     mon Make construct of ".IGNORE :" but has been modified to
  658. X     the notion of an attribute instead of a special target).
  659. X     Not all of the attributes have global meaning.  In particu-
  660. X     lar, .LIBRARY, .NOSTATE, .PHONY, .SETDIR, .SYMBOL and
  661. X     .UPDATEALL have no assigned global meaning.
  662. X
  663. X     Any attribute may be used with any target, even with the
  664. X     special targets.  Some combinations are useless (e.g.
  665. X     .INCLUDE .PRECIOUS: ... ), while others are useful (e.g.
  666. X     .INCLUDE .IGNORE : "file.mk" will not complain if file.mk
  667. X     cannot be found using the include file search rules, see the
  668. X     section on SPECIAL TARGETS for a description of .INCLUDE).
  669. X     If a specified attribute will not be used with the special
  670. X     target a warning is issued and the attribute is ignored.
  671. X
  672. MACROS
  673. X     dmake supports six types of macro assignment.
  674. X
  675. X
  676. X     MACRO = LINE    This is the most common and familiar form of
  677. X                     macro assignment.  It assigns LINE literally
  678. X                     as the value of MACRO.  Future expansions of
  679. X                     MACRO recursively expand its value.
  680. X
  681. X     MACRO *= LINE   This form behaves exactly as the simple '='
  682. X                     form with the exception that if MACRO
  683. X                     already has a value then the assignment is
  684. X                     not performed.
  685. X
  686. X
  687. X
  688. Version 3.70                    UW                             12
  689. X
  690. X
  691. X
  692. X
  693. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  694. X
  695. X
  696. X
  697. X     MACRO := LINE   This form differs from the simple '=' form
  698. X                     in that it expands LINE prior to assigning
  699. X                     it as the value of MACRO.  Future expansions
  700. X                     of MACRO do not recursively expand its
  701. X                     value.
  702. X
  703. X     MACRO *:= LINE  This form behaves exactly as the ':=' form
  704. X                     with the exception that if MACRO already has
  705. X                     a value then the assignment and expansion
  706. X                     are not performed.
  707. X
  708. X     MACRO += LINE   This form of macro assignment allows macro
  709. X                     values to grow.  It takes the literal value
  710. X                     of LINE and appends it to the previous value
  711. X                     of MACRO separating the two by a single
  712. X                     space.  Future expansions of MACRO recur-
  713. X                     sively expand its value.
  714. X
  715. X     MACRO +:= LINE  This form is similar to the '+=' form except
  716. X                     that the value of LINE is expanded prior to
  717. X                     being added to the value of MACRO.
  718. X
  719. X     Macro expressions specified on the command line allow the
  720. X     macro value to be redefined within the makefile only if the
  721. X     macro is defined using the '+=' and '+:=' operators.  Other
  722. X     operators will define a macro that cannot be further modi-
  723. X     fied.
  724. X
  725. X     When dmake defines a non-environment macro it strips leading
  726. X     and trailing white space from the macro value.  Macros
  727. X     imported from the environment via either the .IMPORT special
  728. X     target (see the SPECIAL TARGETS section), or the -e, or -E
  729. X     flags are an exception to this rule.  Their values are
  730. X     always taken literally and white space is never stripped.
  731. X     In addition, named macros defined using the .IMPORT special
  732. X     target do not have their values expanded when they are used
  733. X     within a makefile.  In contrast, environment macros that are
  734. X     imported due to the specification of the -e or -E flags are
  735. X     subject to expansion when used.
  736. X
  737. X     To specify a macro expansion enclose the name in () or {}
  738. X     and precede it with a dollar sign $.  Thus $(TEST)
  739. X     represents an expansion of the macro variable named TEST.
  740. X     If TEST is defined then $(TEST) is replaced by its expanded
  741. X     value.  If TEST is not defined then $(TEST) expands to the
  742. X     NULL string (this is equivalent to defining a macro as
  743. X     'TEST=' ).  A short form may be used for single character
  744. X     named macros.  In this case the parentheses are optional,
  745. X     and $(I) is equivalent to $I.  Macro expansion is recursive,
  746. X     hence, if the value string contains an expression represent-
  747. X     ing a macro expansion, the expansion is performed.  Circular
  748. X     macro expansions are detected and cause an error to be
  749. X
  750. X
  751. X
  752. Version 3.70                    UW                             13
  753. X
  754. X
  755. X
  756. X
  757. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  758. X
  759. X
  760. X
  761. X     issued.
  762. X
  763. X     When defining a macro the given macro name is first expanded
  764. X     before being used to define the macro.  Thus it is possible
  765. X     to define macros whose names depend on values of other mac-
  766. X     ros.  For example, suppose CWD is defined as
  767. X
  768. X          CWD = $(PWD:b)
  769. X
  770. X     then the value of $(CWD) is the name of the current direc-
  771. X     tory.  This can be used to define macros specific to this
  772. X     directory, for example:
  773. X
  774. X          _$(CWD).prt = list of files to print...
  775. X
  776. X     The actual name of the defined macro is a function of the
  777. X     current directory.  A construct such as this is useful when
  778. X     processing a hierarchy of directories using .SETDIR attri-
  779. X     buted targets and a collection of small distributed makefile
  780. X     stubs.
  781. X
  782. X     Macro variables may be defined within the makefile, on the
  783. X     command line, or imported from the environment.
  784. X
  785. X     dmake supports several non-standard macro expansions: The
  786. X     first is of the form:
  787. X
  788. X          $(macro_name:modifier_list:modifier_list:...)
  789. X
  790. X     where modifier_list is chosen from the set { D or d, F or f,
  791. X     B or b, S or s, T or t } and
  792. X
  793. X          d - directory portion of all path names
  794. X          f - file (including suffix) portion of path names
  795. X          b - file (not including suffix) portion of path names
  796. X          s - simple pattern substitution
  797. X          t - tokenization.
  798. X
  799. X     Thus if we have the example:
  800. X
  801. X          test = d1/d2/d3/a.out f.out d1/k.out
  802. X
  803. X     The following macro expansions produce the values on the
  804. X     right of '->' after expansion.
  805. X
  806. X          $(test:d)            -> d1/d2/d3/ d1/
  807. X          $(test:b)            -> a f k
  808. X          $(test:f)            -> a.out f.out k.out
  809. X          ${test:db}           -> d1/d2/d3/a f d1/k
  810. X          ${test:s/out/in/:f}  -> a.in f.in k.in
  811. X          $(test:f:t"+")       -> a.out+f.out+k.out
  812. X
  813. X
  814. X
  815. X
  816. Version 3.70                    UW                             14
  817. X
  818. X
  819. X
  820. X
  821. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  822. X
  823. X
  824. X
  825. X     If a token ends in a string composed from the value of the
  826. X     macro DIRBRKSTR (ie. ends in a directory separator string,
  827. X     e.g. '/' in UNIX) and you use the :d modifier then the
  828. X     expansion returns the directory name less the final direc-
  829. X     tory separator string.  Thus successive pairs of :d modif-
  830. X     iers each remove a level of directory in the token string.
  831. X
  832. X     The tokenization modifier takes all white space separated
  833. X     tokens from the macro value and separates them by the quoted
  834. X     separator string.  The separator string may contain the fol-
  835. X     lowing escape codes \a => <bel>, \b => <backspace>, \f =>
  836. X     <formfeed>, \n => <nl>, \r => <cr>, \t => <tab>, \v =>
  837. X     <vertical tab>, \" => ", and \xxx => <xxx> where xxx is the
  838. X     octal representation of a character.  Thus the expansion:
  839. X
  840. X          $(test:f:t"+\n")
  841. X     produces:
  842. X          a.out+
  843. X          f.out+
  844. X          k.out
  845. X
  846. X     The second non-standard form of macro expansion allows for
  847. X     recursive macros.  It is possible to specify a $(macro_name)
  848. X     or ${macro_name} expansion where macro_name contains more $(
  849. X     ... ) or ${ ... } macro expansions itself.
  850. X
  851. X     For example $(CC$(_HOST)$(_COMPILER)) will first expand
  852. X     CC$(_HOST)$(_COMPILER) to get a result and use that result
  853. X     as the name of the macro to expand.  This is useful for
  854. X     writing a makefile for more than one target environment.  As
  855. X     an example consider the following hypothetical case. Suppose
  856. X     that _HOST and _COMPILER are imported from the environment
  857. X     and are set to represent the host machine type and the host
  858. X     compiler respectively.
  859. X
  860. X          CFLAGS_VAX_CC = -c -O     # _HOST == "_VAX", _COMPILER == "_CC"
  861. X          CFLAGS_PC_MSC = -c -ML # _HOST == "_PC",  _COMPILER == "_MSC"
  862. X
  863. X          # redefine CFLAGS macro as:
  864. X
  865. X          CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
  866. X
  867. X     This causes CFLAGS to take on a value that corresponds to
  868. X     the environment in which the make is being invoked.
  869. X
  870. X     The final non-standard macro expansion is of the form:
  871. X
  872. X          string1{token_list}string2
  873. X
  874. X     where string1, string2 and token_list are expanded.  After
  875. X     expansion, string1 is prepended to each token found in
  876. X     token_list and string2 is appended to each resulting token
  877. X
  878. X
  879. X
  880. Version 3.70                    UW                             15
  881. X
  882. X
  883. X
  884. X
  885. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  886. X
  887. X
  888. X
  889. X     from the previous prepend.  string1 and string2 are not del-
  890. X     imited by white space whereas the tokens in token_list are.
  891. X     A null token in the token list is specified using "".  Thus
  892. X     using another example we have:
  893. X
  894. X          test/{f1 f2}.o     --> test/f1.o test/f2.o
  895. X          test/ {f1 f2}.o    --> test/ f1.o f2.o
  896. X          test/{f1 f2} .o    --> test/f1 test/f2 .o
  897. X          test/{"f1"  ""}.o  --> test/f1.o test/.o
  898. X
  899. X          and
  900. X
  901. X          test/{d1 d2}/{f1 f2}.o --> test/d1/f1.o test/d1/f2.o
  902. X                                     test/d2/f1.o test/d2/f2.o
  903. X
  904. X     This last expansion is activated only when the first charac-
  905. X     ters of token_list appear immediately after the opening '{'
  906. X     with no intervening white space.  The reason for this res-
  907. X     triction is the following incompatibility with Bourne Shell
  908. X     recipes.  The line
  909. X
  910. X          { echo hello;}
  911. X
  912. X     is valid /bin/sh syntax; while
  913. X
  914. X          {echo hello;}
  915. X
  916. X     is not.  Hence the latter triggers the enhanced macro expan-
  917. X     sion while the former causes it to be suppressed.  See the
  918. X     SPECIAL MACROS section for a description of the special mac-
  919. X     ros that dmake defines and understands.
  920. X
  921. RULES AND TARGETS
  922. X     A makefile contains a series of entries that specify depen-
  923. X     dencies.  Such entries are called target/prerequisite or
  924. X     rule definitions.  Each rule definition is optionally fol-
  925. X     lowed by a set of lines that provide a recipe for updating
  926. X     any targets defined by the rule.  Whenever dmake attempts to
  927. X     bring a target up to date and an explicit recipe is provided
  928. X     with a rule defining the target, that recipe is used to
  929. X     update the target.  A rule definition begins with a line
  930. X     having the following syntax:
  931. X
  932. X          <targets> [<attributes>] <ruleop> [<prerequisites>] [;<recipe>]
  933. X
  934. X     targets is a non-empty list of targets.  If the target is a
  935. X     special target (see SPECIAL TARGETS section below) then it
  936. X     must appear alone on the rule line.  For example:
  937. X
  938. X          .IMPORT .ERROR : ...
  939. X
  940. X     is not allowed since both .IMPORT and .ERROR are special
  941. X
  942. X
  943. X
  944. Version 3.70                    UW                             16
  945. X
  946. X
  947. X
  948. X
  949. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  950. X
  951. X
  952. X
  953. X     targets.  Special targets are not used in the construction
  954. X     of the dependency graph and will not be made.
  955. X
  956. X     attributes is a possibly empty list of attributes.  Any
  957. X     attribute defined in the ATTRIBUTES section above may be
  958. X     specified.  All attributes will be applied to the list of
  959. X     named targets in the rule definition.  No other targets will
  960. X     be affected.
  961. X
  962. X
  963. X     NOTE:   As stated earlier, if both the target list and
  964. X             prerequisite list are empty but the attributes list
  965. X             is not, then the specified attributes affect all
  966. X             targets in the makefile.
  967. X
  968. X
  969. X     ruleop is a separator which is used to identify the targets
  970. X     from the prerequisites.  Optionally it also provides a
  971. X     facility for modifying the way in which dmake handles the
  972. X     making of the associated targets.  In its simplest form the
  973. X     operator is a single ':', and need not be separated by white
  974. X     space from its neighboring tokens.  It may additionally be
  975. X     followed by any of the modifiers { !, ^, -, : }, where:
  976. X
  977. X
  978. X     !    says execute the recipe for the associated targets once
  979. X          for each out of date prerequisite.  Ordinarily the
  980. X          recipe is executed once for all out of date prere-
  981. X          quisites at the same time.
  982. X
  983. X     ^    says to insert the specified prerequisites, if any,
  984. X          before any other prerequisites already associated with
  985. X          the specified targets.  In general, it is not useful to
  986. X          specify ^ with an empty list of prerequisites.
  987. X
  988. X     -    says to clear the previous list of prerequisites before
  989. X          adding the new prerequisites.  Thus,
  990. X
  991. X               .SUFFIXES :
  992. X               .SUFFIXES : .a .b
  993. X
  994. X          can be replaced by
  995. X
  996. X               .SUFFIXES :- .a .b
  997. X
  998. X          however the old form still works as expected.  NOTE:
  999. X          .SUFFIXES is ignored by dmake it is used here simply as
  1000. X          an example.
  1001. X
  1002. X     :    When the rule operator is not modified by a second ':'
  1003. X          only one set of rules may be specified for making a
  1004. X          target.  Multiple definitions may be used to add to the
  1005. X
  1006. X
  1007. X
  1008. Version 3.70                    UW                             17
  1009. X
  1010. X
  1011. X
  1012. X
  1013. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1014. X
  1015. X
  1016. X
  1017. X          list of prerequisites that a target depends on.  How-
  1018. X          ever, if a target is multiply defined only one defini-
  1019. X          tion may specify a recipe for making the target.
  1020. X
  1021. X          When a target's rule operator is modified by a second
  1022. X          ':' (:: for example) then this definition may not be
  1023. X          the only definition with a recipe for the target.
  1024. X          There may be other :: target definition lines that
  1025. X          specify a different set of prerequisites with a dif-
  1026. X          ferent recipe for updating the target. Any such target
  1027. X          is made if any of the definitions find it to be out of
  1028. X          date with respect to the related prerequisites and the
  1029. X          corresponding recipe is used to update the target.
  1030. X
  1031. X          In the following simple example, each rule has a `::'
  1032. X          ruleop.  In such an operator we call the first `:' the
  1033. X          operator, and the second `:' the modifier.
  1034. X
  1035. X          a.o :: a.c b.h
  1036. X             first recipe for making a.o
  1037. X
  1038. X          a.o :: a.y b.h
  1039. X             second recipe for making a.o
  1040. X
  1041. X          If a.o is found to be out of date with respect to a.c
  1042. X          then the first recipe is used to make a.o.  If it is
  1043. X          found out of date with respect to a.y then the second
  1044. X          recipe is used.  If a.o is out of date with respect to
  1045. X          b.h then both recipes are invoked to make a.o.  In the
  1046. X          last case the order of invocation corresponds to the
  1047. X          order in which the rule definitions appear in the
  1048. X          makefile.
  1049. X
  1050. X     Targets defined using a single `:' operator with a recipe
  1051. X     may be redefined again with a new recipe by using a `:'
  1052. X     operator with a `:' modifier.  This is equivalent to a tar-
  1053. X     get having been initially defined with a rule using a `:'
  1054. X     modifier.  Once a target is defined using a `:' modifier it
  1055. X     may not be defined again with a recipe using only the `:'
  1056. X     operator with no `:' modifier.  In both cases the use of a
  1057. X     `:' modifier creates a new list of prerequisites and makes
  1058. X     it the current prerequisite list for the target.  The `:'
  1059. X     operator with no recipe always modifies the current list of
  1060. X     prerequisites.  Thus assuming each of the following defini-
  1061. X     tions has a recipe attached, then:
  1062. X
  1063. X          joe :  fred ...     (1)
  1064. X          joe :: more ...     (2)
  1065. X
  1066. X          and
  1067. X
  1068. X          joe :: fred ...     (3)
  1069. X
  1070. X
  1071. X
  1072. Version 3.70                    UW                             18
  1073. X
  1074. X
  1075. X
  1076. X
  1077. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1078. X
  1079. X
  1080. X
  1081. X          joe :: more ...     (4)
  1082. X
  1083. X     are legal and mean:  add the recipe associated with (2), or
  1084. X     (4) to the set of recipes for joe, placing them after exist-
  1085. X     ing recipes for making joe.  The constructs:
  1086. X
  1087. X          joe :: fred ...     (5)
  1088. X          joe : more ... (6)
  1089. X
  1090. X          and
  1091. X
  1092. X          joe : fred ... (7)
  1093. X          joe : more ... (8)
  1094. X
  1095. X     are errors since we have two sets of perfectly good recipes
  1096. X     for making the target.
  1097. X
  1098. X     prerequisites is a possibly empty list of targets that must
  1099. X     be brought up to date before making the current target.
  1100. X
  1101. X     recipe is a short form and allows the user to specify short
  1102. X     rule definitions on a single line.  It is taken to be the
  1103. X     first recipe line in a larger recipe if additional lines
  1104. X     follow the rule definition.  If the semi-colon is present
  1105. SHAR_EOF
  1106. true || echo 'restore of dmake/man/dmake.nc failed'
  1107. fi
  1108. echo 'End of part 14, continue with part 15'
  1109. echo 15 > _shar_seq_.tmp
  1110. exit 0
  1111. exit 0 # Just in case...
  1112.